Warmers de API

Mantén calientes los endpoints REST y GraphQL, con métodos, cabeceras, cookies, cuerpos y matrices de configuración reales.

13 min read

Las API se enfrían exactamente como lo hacen las páginas web. Si una respuesta JSON es costosa de crear y se almacena en caché en tu CDN o puerta de enlace, el primer cliente después de tu vencimiento paga la misma penalización que pagaría un visitante del sitio web.

API warmers resuelve eso. Se administran por separado desde el sitio web warmers, en Cuenta → API Warmers, y tienen tus propios límites de plan.

Separado del sitio web warmers

API warmers es una característica distinta con tu propio derecho. Si falta la sección o está bloqueada, tu plan no la incluye; consulte Planes y límites.

Cuando usar uno

Situación	Por qué ayuda una API warmer
Un escaparate o sitio sin cabeza	El JSON de producto, inventario y contenido se recupera en cada representación de página. Calentar esas rutas mantiene rápida toda la parte delantera.
Una API de desarrollador pública	Los puntos finales populares y los ejemplos de documentación siguen respondiendo en lugar de ser lentos para quien llama primero.
Una capa backend-for-frontend	Los puntos finales agregados que se distribuyen en varios servicios son costosos de reconstruir. Calentarlos protege a los clientes móviles y web.
Operaciones pesadas GraphQL	Un puñado de consultas suelen dominar el tráfico. Calentar esas operaciones específicas es mucho más importante que presionar `/graphql` una vez.

Una API warmer no es útil para puntos finales que nunca se almacenan en caché o que son únicos por usuario y, por lo tanto, no tienen una copia en caché compartida para completar.

Creando una API warmer

1
Verificar la API hostname
Las URL de los puntos finales deben utilizar un hostname verificado, exactamente como el sitio web warmers. Consulte Hostname verificación.
2
Nombra el warmer y déjalo inactivo
Configure primero, actívelo cuando esté satisfecho.
3
Agregar uno o más puntos finales
Cada punto final tiene una URL y un método HTTP y, opcionalmente, una etiqueta, un cuerpo y un tipo de contenido.
4
Agregue autenticación si el punto final la necesita
Los encabezados globales y las cookies se aplican a cada solicitud que realiza el warmer.
5
Opcionalmente expandir con una matriz de configuración
Cubre muchas variantes (localidades, inquilinos, identificaciones) sin crear docenas de warmers casi idénticos.
6
Establezca la velocidad y los intervalos, luego active
La misma idea que el sitio web warmers: calentar con la frecuencia suficiente para superar el TTL de tu caché, lo suficientemente lento como para no dañar.

Puntos finales

Cada punto final en warmer se configura de forma independiente:

Etiqueta: Un nombre opcional legible por humanos, para que una larga lista de puntos finales siga siendo legible.
URL: La dirección completa del punto final en un hostname verificado. Puede contener marcadores de posición de ruta como {id} o :id cuando se combinan con una dimensión de RUTA.
Método: GET, POST y otros según tu plan. Los planes suelen permitir GET y HEAD de forma predeterminada, con más métodos en niveles superiores.
Protocolo: REST o GRAPHQL. Al elegir GraphQL se revelan los campos de operación y consulta.
Solicitar plantilla de cuerpo: El cuerpo a enviar, para los métodos que lo llevan. Requiere el derecho del cuerpo de solicitud de API.
Tipo de contenido: El tipo de contenido del cuerpo de la solicitud, normalmente application/json.
idempotente: Marca el punto final como seguro para llamar dos veces, lo que permite la doble búsqueda fría/cálida que mide la mejora. Habilítelo solo cuando llamar dos veces realmente no tiene efectos secundarios.
Habilitado: Si este punto final específico está incluido en las ejecuciones. Útil para deshabilitar temporalmente un punto final sin eliminarlo.

Tenga cuidado al marcar operaciones de escritura idempotentes

Una recuperación doble en un punto final que crea pedidos, envía correos electrónicos o cobra tarjetas lo hará dos veces. Sólo marque un punto final idempotente cuando repetirlo sea realmente inofensivo.

Matrices de configuración

La mayoría de las API tienen variantes: el mismo punto final llamado por configuración regional, por inquilino, por moneda o por ID. Crear un warmer para cada uno no se puede mantener.

Una matriz de configuración resuelve esto. Tú define dimensiones con múltiples valores y Cache Rocket expande el producto cartesiano completo en solicitudes cálidas individuales.

Tipo de dimensión	Inyecta valores en	Ejemplo
`QUERY`	La cadena de consulta	`locale=en`, `locale=nl`, `locale=de`
`HEADER`	Un encabezado de solicitud	`X-Tenant: acme`, `X-Tenant: globex`
`COOKIE`	una galleta	`currency=EUR`, `currency=USD`
`PATH`	Un `{placeholder}` en la URL	`{id}` → `1`, `2`, `3`

Un ejemplo trabajado

text

Endpoint:  GET https://api.example.com/v1/products/{category}

Dimensions:
  PATH   category = shoes, bags, hats
  QUERY  locale   = en, nl

Expands to 6 warm requests:
  /v1/products/shoes?locale=en
  /v1/products/shoes?locale=nl
  /v1/products/bags?locale=en
  /v1/products/bags?locale=nl
  /v1/products/hats?locale=en
  /v1/products/hats?locale=nl

Las combinaciones se multiplican rápido

El total de solicitudes es el producto del recuento de valores de cada dimensión. Tres dimensiones de cinco valores cada una son 125 combinaciones desde un único punto final. El formulario muestra un recuento acumulado y el máximo de tu plan; obsérvelo a medida que agrega valores.

Si excede el máximo del plan, el warmer no se guardará. Reduzca los valores, divídalos en varios warmers o actualice.

Autenticación

Los encabezados de solicitud y las cookies globales se aplican a cada variante que genera warmer. Aquí es donde va un encabezado Authorization o una cookie de sesión.

Encabezados de autenticación típicos

text

Authorization: Bearer YOUR_LONG_LIVED_TOKEN
X-Api-Key: YOUR_API_KEY

Calentar la variante que los clientes reales realmente solicitan

Si tu caché varía en Authorization, el calentamiento con un token de servicio llena una entrada de caché asociada a ese token, que ningún cliente real accederá jamás. Para respuestas compartidas que se pueden almacenar en caché, caliente de la misma manera que un cliente común llama al punto final.

Los tokens caducan. Si una API warmer de repente comienza a devolver 401, lo primero que debe verificar es un token codificado.

GraphQL

GraphQL necesita tu propio tratamiento porque el rendimiento depende de la operación específica, no de la ruta del punto final. Pulsar /graphql una vez no te dice nada; Calentar tus tres consultas más importantes te lo dice todo.

Establezca el protocolo de un punto final en GraphQL, luego proporcione:

Operación GraphQL: ya sea un query o un mutation. Las mutaciones que se calientan casi nunca son apropiadas.
GraphQL consulta: el documento de operación a enviar.
Variables: proporciónelas a través de la plantilla del cuerpo de la solicitud o como valores de dimensiones de matriz para calentar varios conjuntos de variables.

Note

El calentamiento GraphQL está controlado por tu propio derecho de plan, además de API warmers.

Importación de API abierta

En los planes compatibles, puede importar puntos finales directamente desde una especificación OpenAPI 3 en lugar de escribirlos. Pegue la URL de una especificación JSON o YAML y haga clic en Importar; Los puntos finales descubiertos se agregan al warmer, listos para podar y ajustar.

Tip

La importación incluye todo lo que describe la especificación, incluidas las operaciones de escritura. Revise la lista cuidadosamente y desactive todo lo que no deba llamarse en un horario antes de activarlo.

Límites y programación

Calentamiento máximo por minuto: Límite de velocidad para esta API warmer, equivalente al máximo de URL por minuto en un sitio web warmer.
Solicitar tiempo de espera: Cuánto tiempo esperar una respuesta antes de darse por vencido.
Intervalo de inicio automático: Con qué frecuencia comienza un nuevo pase cálido, en segundos.
Intervalo de puesta en cola: Ritmo del trabajo vuelto a poner en cola dentro del ciclo.
Reescribir en HTTPS: Actualice http:// URL de punto final a https://.
Horario cálido: Ventanas pico y valle, mismo formato JSON que el sitio web warmers. Consulte Calentamiento avanzado.

Su plan también limita la cantidad de API warmers, puntos finales por warmer y combinaciones por warmer.

Problemas comunes

Todo vuelve 401 o 403.: El encabezado de autenticación o la cookie faltan, son incorrectos o han caducado. Los tokens de larga duración son los culpables habituales: compruebe que el token sigue siendo válido y no ha rotado.
El warmer no se guardará, citando demasiadas combinaciones.: Su matriz se expande más allá del máximo del plan. Reduzca los valores de dimensión, divida los puntos finales en varios warmers o actualice.
El método que necesito no está en el menú desplegable.: Los planes restringen qué métodos HTTP están permitidos. Los niveles inferiores normalmente solo permiten GET y HEAD.
El calentamiento se ejecuta limpiamente, pero las respuestas aún son lentas para los clientes reales.: Probablemente esté completando una variante de caché diferente a la que solicitan los clientes, generalmente debido a un encabezado Authorization, una cookie o un encabezado en el que varía tu CDN. Compare la solicitud exacta que envía un cliente real con la que envía el warmer.
¿Puedo activar un punto final que requiere un token firmado y de corta duración?: No es confiable, porque warmer no puede generar una firma nueva por ejecución. Exponga una variante no autenticada que se puede almacenar en caché o utilice un token de servicio de larga duración donde sea seguro.